# Permission Set

Applies or updates permissions on SharePoint sites, document libraries, and folders. Accepts either an Excel file (one row per object) or a JSON file (single object).

Filename pattern:

Excel: filename must contain permissionset or permissionsset (case-insensitive).
Example: 20240115 permissionset matters.xlsx
JSON: filename must contain PermissionSet with a .json extension.
Example: PermissionSet.json

# Excel format

# Targeting

Each row must identify the site to connect to and, optionally, the specific object to apply permissions to.

Name	Required	Description
MatterCode	Conditional	Matter identifier. Required when SiteUrl and Url are not provided. Resolves the site URL from the matter list.
ClientCode	No	Client identifier used together with MatterCode to resolve the matter.
SiteUrl / WebUrl	Conditional	Direct URL of the SharePoint site. Required when MatterCode is not provided and Url does not contain a site URL.
Url	Conditional	URL of the site, library, or folder. When SiteUrl and MatterCode are both absent, the handler uses Url as the site URL.
ObjectUrl	No	Specific object (folder or document) within the resolved site to apply permissions to.
Folder	No	Folder path within the matter's document library. When the matter has exactly one document library, the folder path is combined with the doclib URL.

# Permission source

Name	Required	Description
PermissionSet	Conditional	Name of a `PermissionSetCfg` defined in config.json. Roles and members are taken from the configuration. Required when no `DomainMembers.` or `Groups.` columns are present.
DomainMembers.`<RoleName>`	No	Semicolon-separated list of domain users or groups to assign to `<RoleName>`.
Groups.`<RoleName>`	No	Semicolon-separated list of SharePoint group names to assign to `<RoleName>`.

<RoleName> must match a role in the referenced PermissionSetCfg or be a SharePoint built-in role type (opens new window) (Reader, Contributor, Full Control).

Both approaches can be combined: use PermissionSet to define the role structure and add DomainMembers.* or Groups.* columns to override members per row.

# Behavior overrides

These columns override the corresponding settings from the referenced PermissionSetCfg for that row:

Name	Required	Description
DisableInheritance	No	Boolean. Break permission inheritance on the target object.
CopyRoleAssignments	No	Boolean. When breaking inheritance, copy the parent's role assignments first.
ResetPermissions / ResetPermission	No	Boolean. Remove all existing role assignments before applying new ones. See warning below.
RemoveCurrentPermissions / RemovePermissions / RemoveCurrentPermission / RemovePermission	No	Boolean. Remove all current permissions.
ReAssignPermissions / ReAssignPermission	No	Boolean. Force reapplication of permissions even if the object already has the correct assignments.

⚠️ Warning — ResetPermissions permanently deletes existing permissions on the target and all child objects

When ResetPermissions is set to true, all unique role assignments on the target object are permanently removed before the new permissions are applied. This includes any manually configured permissions that are not inherited from a parent site or library — they cannot be recovered after deletion.

Child objects are also affected. When the target object currently inherits permissions (no unique assignments of its own), the reset uses SharePoint's clearSubscopes flag when breaking inheritance. This forces all child objects — including subfolders and individual files — that have their own unique permissions to also lose those permissions and revert to inheriting from the parent. Any per-file or per-subfolder permissions configured manually will be permanently removed.

If the provisioning operation fails after the reset step, the target object and any affected children are left without permissions until a successful run completes.

Only use ResetPermissions when you intentionally want to replace the full permission set from scratch. If you only want to add or update specific members, use ReAssignPermissions instead.

See the Microsoft documentation on SharePoint permission levels (opens new window) and BreakRoleInheritance (opens new window) for background on unique vs. inherited permissions and the clearSubscopes behaviour.

# Example

ClientCode	MatterCode	PermissionSet	DisableInheritance	CopyRoleAssignments	DomainMembers.Contribute	Groups.Read
ACME	00123	MatterSite	true	false	alice@contoso.com	Matter Readers
ACME	00124	MatterSite	true	false	bob@contoso.com; carol@contoso.com

# JSON format

A JSON file with a .json extension. Fields:

Field	Required	Description
MatterCode	Conditional	Matter identifier. Required when SiteUrl is not provided.
ClientCode	No	Client identifier used together with MatterCode.
SiteUrl	Conditional	Direct URL of the SharePoint site. Required when MatterCode is not provided.
ObjectUrl	No	Specific object within the site to apply permissions to.
Folder	No	Folder path within the matter's document library.
PermissionSet	No	Name of a `PermissionSetCfg` in config.json.
DisableInheritance	No	Boolean.
ResetPermissions	No	Boolean.
RemoveCurrentPermissions	No	Boolean.
CopyRoleAssignments	No	Boolean.
Roles	No	Array of role objects. Each has `RoleType` (or `Name`) and either `DomainMembers` or `Groups` (string arrays).

Example:

{
  "MatterCode": "32211",
  "RemoveCurrentPermissions": true,
  "Roles": [
    { "RoleType": "Editor", "DomainMembers": ["Everyone"] },
    { "RoleType": "Contributor", "Groups": ["DMS Admin"] }
  ]
}

PermissionSetCfg — defines named permission sets referenced by this handler